feat(wallet): Add split persistence backed by better-sqlite3 by rekmarks · Pull Request #8480 · MetaMask/core

rekmarks · 2026-04-16T02:06:13Z

Summary

Add synchronous, per-property SQLite persistence to the wallet package using better-sqlite3
Each controller state property with persist: true metadata gets its own row in a kv table (key format: ControllerName.propertyName)
Writes happen synchronously within the same call stack as controller.update() via stateChanged event subscriptions, eliminating data loss windows
Defaults to :memory: when no database path is provided

Test plan

yarn workspace @metamask/wallet exec jest --no-coverage --watchman=false src/persistence/ — 22 unit tests covering KeyValueStore CRUD, loadState grouping, persist filtering, StateDeriver application, patch-based diffing, unsubscribe, and multi-controller scenarios
yarn workspace @metamask/wallet exec tsc --noEmit — no new type errors
Integration test with file-backed DB: create Wallet with a file path, perform operations, create second Wallet from same path, verify state restoration

🤖 Generated with Claude Code

Note

Medium Risk
Introduces a new persistence layer and changes wallet lifecycle/messenger semantics, plus adds a native dependency (better-sqlite3) that can affect build/install reliability across environments.

Overview
Adds a new persistence subpath export that provides synchronous SQLite-backed state storage via KeyValueStore, plus loadState (reconstruct controller state from Controller.prop keys) and subscribeToChanges (persist only persist-flagged controller properties based on Immer patches and delete on removal).

Updates Wallet construction/typing to accept optional preloaded state, exposes controllerMetadata for initialized controllers, switches messenger namespace to Wallet, and makes destroy() idempotent while publishing a new Wallet:destroyed event after best-effort controller teardown.

Wires in the native better-sqlite3 dependency (with LavaMoat allow-scripts), adds test/CI setup to install required binaries (anvil + better-sqlite3 prebuild) and documents how to rebuild the native addon.

^{Reviewed by Cursor Bugbot for commit 772c1e6. Bugbot is set up for automated code reviews on this repo. Configure here.}

socket-security · 2026-04-16T02:07:01Z

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	@types/better-sqlite3@7.6.13
	better-sqlite3@12.9.0

View full report

rekmarks · 2026-04-16T02:38:53Z

@SocketSecurity ignore npm/better-sqlite3@11.10.0

Yes, it has native binaries.

rekmarks · 2026-04-16T02:48:10Z

@SocketSecurity ignore-all

All alerts are due to better-sqlite3 or its transitives. It is a reputable package that we use elsewhere.

Persist controller state to SQLite using a per-property key-value scheme (one row per ControllerName.propertyName). Writes are synchronous within the same call stack as controller state updates, using stateChanged events and Immer patches to write only changed, persist-flagged properties. Defaults to ':memory:' when no database path is provided. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

The build tsconfig is stricter than the dev tsconfig — the union type of controller instances does not expose the protected `destroy` method. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Address review findings: add constructor cleanup on failure, make destroy() idempotent with Promise.allSettled and finally, handle remove patches via store.delete(), catch and log handler write failures, validate degenerate store keys, handle root state replacement patches, add contextful JSON.parse errors, tighten loadState return type, extract PersistableController type and storeKey utility, remove premature KeyValueStore public export, and add tests for new behaviors. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Make `@metamask/wallet` platform-agnostic by removing the SQLite-backed `KeyValueStore` from the `Wallet` constructor. `Wallet` now accepts a flat `WalletOptions` (including an optional `state` payload) and owns no persistence state. Consumers arrange persistence themselves. - `Wallet` exposes a `controllerMetadata` getter so persistence can operate on metadata alone, without reaching into controller instances. - A new `Root:walletDestroyed` event is published after controllers tear down during `destroy()`. `subscribeToChanges` listens for it and self-unsubscribes, eliminating the need for callers to hold an unsubscribe handle. - `subscribeToChanges` now takes a `Record<string, StateMetadataConstraint>` instead of the controller-instance map, and specializes its messenger type to `RootMessenger<DefaultActions, DefaultEvents>` so subscribing to `Root:walletDestroyed` type-checks without suppression. - `KeyValueStore`, `loadState`, and `subscribeToChanges` are exposed via a new `@metamask/wallet/persistence` subpath export; they'll move to their own package later.

So that @metamask/wallet/persistence can be moved to its own package without needing to deep-import from the wallet package.

Renames install-anvil.sh to install-binaries.sh and adds a better-sqlite3 native addon rebuild step for CI environments where the prebuilt binding is absent or incompatible with the Node version. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Check for the compiled addon at `node_modules/better-sqlite3/build/Release/better_sqlite3.node` and skip `prebuild-install` when it's already present. Avoids unnecessary network calls on every `test:prepare` run. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

cursor

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 4c16ea9. Configure here.}

FrederikBolding · 2026-04-21T09:12:09Z

+      const changed = getChangedProperties(patches, persistedProperties);
+
+      for (const prop of changed) {
+        const key = storeKey(controllerName, prop);


The clients do persistence using KV where the key is the controller name. Do we think it is preferable to do at the property level? If so, why?

It's faster. SQLite stores a text representation of the JSON values under the hood. Every time we modify a value stored at a given key in the state table, we overwrite the value of that key with JSON.stringify(newValue) (see KeyValueStore.ts). Consequently, by splitting controller state across multiple keys, there is less persistence overhead. There are ways to make this vastly more efficient, but this should be fine for know.

I don't know what the tradeoffs look like for this in the browser or React Native.

FrederikBolding · 2026-04-21T09:13:47Z

+  persistedProperties: ReadonlySet<string>,
+): ReadonlySet<string> {
+  const changed = new Set<string>();
+  for (const patch of patches) {


Generally we try to not inspect the patches as it has proven error-prone, it may be fine in this case, but flagging regardless.

I hear that, although in this case we're not deeply inspecting the patches but relying on a couple of invariants:

If the patch path length is 0, the entire value has been replaced

The first element of the path array is the name of the first modified property

This comment was marked as resolved.

Sign in to view

rekmarks added the no-changelog label Apr 16, 2026

rekmarks force-pushed the rekm/wallet-sqlite branch 6 times, most recently from 8f58b8c to f66328d Compare April 16, 2026 20:30

rekmarks force-pushed the feat/wallet-library branch 2 times, most recently from 623f9af to 3fb60ee Compare April 16, 2026 21:13

rekmarks force-pushed the rekm/wallet-sqlite branch 4 times, most recently from 1d6d1fc to 937ba80 Compare April 16, 2026 21:52

rekmarks marked this pull request as ready for review April 16, 2026 21:59

rekmarks requested a review from a team as a code owner April 16, 2026 21:59

rekmarks force-pushed the rekm/wallet-sqlite branch from 937ba80 to 29c6ac6 Compare April 16, 2026 21:59

cursor Bot reviewed Apr 16, 2026

View reviewed changes

Comment thread packages/wallet/src/persistence/persistence.ts

cursor Bot reviewed Apr 16, 2026

View reviewed changes

Comment thread packages/wallet/src/Wallet.ts Outdated

rekmarks force-pushed the rekm/wallet-sqlite branch from 0cf2d0d to 520a971 Compare April 17, 2026 03:28

FrederikBolding force-pushed the feat/wallet-library branch from 45d013e to 6ec54b9 Compare April 17, 2026 09:30

FrederikBolding reviewed Apr 17, 2026

View reviewed changes

Comment thread packages/wallet/src/Wallet.ts Outdated

FrederikBolding reviewed Apr 17, 2026

View reviewed changes

Comment thread packages/wallet/src/persistence/persistence.ts Outdated

rekmarks and others added 4 commits April 17, 2026 11:50

fix(wallet): Restore @ts-expect-error for protected destroy access

0b122f7

The build tsconfig is stricter than the dev tsconfig — the union type of controller instances does not expose the protected `destroy` method. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

chore: Bump better-sqlite3

331ef42

chore: lint

283acca

rekmarks and others added 8 commits April 17, 2026 11:50

docs: Fix better-sqlite3 rebuild instructions

18b57d1

refactor: Tweak sqlite imports

b6b0596

refactor: Tweak types, simplify tests

428d427

tests: Cover persistence error paths and lifecycle edge cases

c6a88f5

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

chore: oxfmt & eslint

62ff2e3

refactor: Make change and persist sets readonly

6df4a99

refactor: Unsubscribe in try block

cfad387

rekmarks force-pushed the rekm/wallet-sqlite branch from 520a971 to cfad387 Compare April 17, 2026 18:50

cursor Bot reviewed Apr 17, 2026

View reviewed changes

Comment thread packages/wallet/src/Wallet.ts Outdated

rekmarks added 3 commits April 17, 2026 14:49

chore: Re-export persistence-facing types from wallet entry

366b265

So that @metamask/wallet/persistence can be moved to its own package without needing to deep-import from the wallet package.

fix: Prevent synchronous errors from interrupting destroy procedure

f4e8dfa

rekmarks force-pushed the rekm/wallet-sqlite branch from 06b91f1 to f4e8dfa Compare April 17, 2026 22:00

rekmarks and others added 3 commits April 17, 2026 15:07

test: Add tests for destruction robustuness

86a69b0

rekmarks requested a review from FrederikBolding April 17, 2026 22:49

refactor: Exclude instances without metadata from metadata getter

4c16ea9

cursor Bot reviewed Apr 20, 2026

View reviewed changes

Comment thread packages/wallet/src/Wallet.ts

refactor: Remove extraneous registerInitialEventPayload

58ab0c5

FrederikBolding reviewed Apr 21, 2026

View reviewed changes

Comment thread packages/wallet/src/Wallet.ts Outdated

FrederikBolding reviewed Apr 21, 2026

View reviewed changes

Comment thread packages/wallet/src/Wallet.test.ts Outdated

FrederikBolding reviewed Apr 21, 2026

View reviewed changes

Comment thread packages/wallet/src/Wallet.ts Outdated

refactor: Address review

772c1e6

FrederikBolding approved these changes Apr 22, 2026

View reviewed changes

FrederikBolding merged commit 39b963d into feat/wallet-library Apr 22, 2026
349 checks passed

FrederikBolding deleted the rekm/wallet-sqlite branch April 22, 2026 08:23

Uh oh!

Conversation

rekmarks commented Apr 16, 2026 • edited by cursor Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Test plan

Uh oh!

socket-security Bot commented Apr 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

This comment was marked as resolved.

rekmarks commented Apr 16, 2026

Uh oh!

rekmarks commented Apr 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

FrederikBolding Apr 21, 2026

Choose a reason for hiding this comment

Uh oh!

rekmarks Apr 21, 2026

Choose a reason for hiding this comment

Uh oh!

FrederikBolding Apr 21, 2026

Choose a reason for hiding this comment

Uh oh!

rekmarks Apr 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

rekmarks commented Apr 16, 2026 •

edited by cursor Bot

Loading

socket-security Bot commented Apr 16, 2026 •

edited

Loading

rekmarks commented Apr 16, 2026 •

edited

Loading

rekmarks Apr 21, 2026 •

edited

Loading